OpenClaw系列第20课：Heartbeat - 保持 Agent 活跃的机制

这是「OpenClaw 教程课程」第 20 课。
第 18 课我们讲了 Cron：按时间执行明确任务。第 19 课讲了 Webhook / Hooks：由外部或内部事件触发。今天讲第四模块最后一个关键概念：Heartbeat。

图：Heartbeat 像 Agent 的周期性轻量检查机制。它不是专门跑定时任务，而是让 Agent 定期醒来看看有没有需要提醒用户的事情。

很多人第一次看到 Heartbeat，会把它理解成：

“这不就是另一个 Cron 吗？”

不是。

Heartbeat 和 Cron 都和“定时”有关，但它们的目标不一样。

Cron 更像闹钟：

到点执行一个明确任务。

Heartbeat 更像轻量巡检：

定期醒来看看有没有需要注意的事，如果没有就安静。

这节课我们要讲清楚：

Heartbeat 是什么，什么时候该用，什么时候不该用，怎么写 HEARTBEAT.md，以及怎样避免它变成打扰。

一、Heartbeat 是什么？

OpenClaw 文档里对 Heartbeat 的描述很关键：

Heartbeat runs periodic agent turns in the main session so the model can surface anything that needs attention without spamming you.

翻译成新手能理解的话：

Heartbeat 会周期性让 Agent 在主会话里醒来一次，看看有没有需要提醒你的事情。

它的目标不是“每次都发消息”。

它的目标是：

  • 有事就提醒
  • 没事就安静
  • 避免 spam
  • 让 Agent 能处理一些后台完成事件或轻量检查

所以 Heartbeat 的核心不是“定时执行任务”。

而是：

周期性检查是否需要出声。

二、Heartbeat 和 Cron 最大的区别

这个区别一定要先讲清楚。

Cron：到点做明确任务

例如：

1
每天早上 8 点生成晨报。

或者：

1
每周一检查文章格式。

Cron 的特点是：

  • 有明确任务
  • 有明确时间
  • 每次触发就是为了执行这个任务
  • 会创建 background task 记录
  • 适合报告、提醒、周期检查

Heartbeat：周期性看看有没有事

例如：

1
每 30 分钟醒来一次，看看有没有 urgent follow-up。

Heartbeat 的特点是：

  • 更像巡检
  • 通常跑在 main session
  • 本身不创建 background task 记录
  • 没事应该返回 HEARTBEAT_OK
  • 适合轻量检查、背景提醒、关注未处理事项

一句话：

Cron 是“到点做事”，Heartbeat 是“定期看看有没有事”。

图：Cron 更像闹钟，适合明确任务；Heartbeat 更像心跳巡检，适合周期性检查是否需要提醒。

三、Heartbeat 不是 Background Task

第 16、17、18 课里，我们多次讲到 background tasks。

这里要特别说明：

Heartbeat 本身不会创建 background task 记录。

文档里说得很明确：

  • ACP runs 会创建 task
  • subagent spawns 会创建 task
  • cron executions 会创建 task
  • CLI operations 会创建 task
  • Heartbeat turns 不会创建 task
  • 普通聊天也不会创建 task

所以你可以这样理解：

Cron 是后台任务调度器，执行后会进 task ledger；Heartbeat 是主会话周期性唤醒机制，不是 task ledger 里的任务。

不过，Heartbeat 可以响应后台任务完成事件。

例如某个 detached work 完成后，系统可能唤醒 Heartbeat，让主会话注意到结果。

但 Heartbeat 自己不是一个 detached task。

四、默认 Heartbeat 做什么？

文档里提到默认 prompt 大意是：

1
2
3
Read HEARTBEAT.md if it exists. Follow it strictly.
Do not infer or repeat old tasks from prior chats.
If nothing needs attention, reply HEARTBEAT_OK.

这里有几个关键点。

1）会读取 HEARTBEAT.md

如果工作区有 HEARTBEAT.md，默认 prompt 会让 Agent 读取它。

它像一个“心跳检查清单”。

2）不要从旧聊天里瞎推任务

这点很重要。

Heartbeat 不应该根据很久以前的聊天内容自己脑补任务。

它应该只按当前明确配置和 HEARTBEAT.md 做事。

3）没事就 HEARTBEAT_OK

如果没有需要提醒的事情，应该回复：

1
HEARTBEAT_OK

OpenClaw 会把这种 OK-only 回复识别为静默确认，并通常不投递给用户。

所以 Heartbeat 理想状态是：

大多数时候安静，真的有事才说话。

图：Heartbeat 定期醒来，读取 HEARTBEAT.md 和必要上下文；如果没事返回 HEARTBEAT_OK，有事才发送提醒。

五、HEARTBEAT_OK 是什么？

HEARTBEAT_OK 是 Heartbeat 的静默确认信号。

它表示：

我检查过了，目前没有需要打扰用户的事情。

文档里说，Heartbeat 运行中，如果回复开头或结尾出现 HEARTBEAT_OK，OpenClaw 会把它当作 ack。

如果剩余内容很短，通常会丢弃这条回复，不对外发送。

这就是 Heartbeat 能“少打扰”的关键机制。

什么时候不要写 HEARTBEAT_OK？

如果真的有 alert，就不要带 HEARTBEAT_OK。

例如：

1
检测到 Gateway 状态异常，请查看 openclaw gateway status。

这类就应该直接发 alert。

不要写：

1
HEARTBEAT_OK 但是 Gateway 有异常。

因为语义冲突。

简单记：

没事才 OK，有事就直接说事。

六、HEARTBEAT.md 是什么？

HEARTBEAT.md 是工作区里的一个可选文件。

它用于告诉 Heartbeat：

每次心跳时应该检查什么。

文档里的模板很简单：

1
2
3
# Keep this file empty (or with only comments) to skip heartbeat API calls.

# Add tasks below when you want the agent to check something periodically.

也就是说：

  • 空文件或只有注释，可以跳过 heartbeat API call
  • 写入任务后，Heartbeat 才有明确检查内容

你可以把它理解成：

给 Agent 的心跳待办清单。

七、HEARTBEAT.md 应该怎么写？

一个好的 HEARTBEAT.md 应该：

  • 很短
  • 很稳定
  • 很安全
  • 不放敏感信息
  • 不写模糊大任务
  • 不让 Agent 每次都长篇汇报

例如：

1
2
3
4
5
# Heartbeat checklist

- 如果有后台任务完成但还没通知用户，请用一句话提醒。
- 如果发现教程写作任务被阻塞，请说明缺少什么输入。
- 如果没有需要提醒的事，回复 HEARTBEAT_OK。

这就很好。

不要写成：

1
2
3
# Heartbeat checklist

- 每次都完整检查所有项目、所有日志、所有消息、所有文章，并写一份详细报告。

这样会很重，也会很烦。

Heartbeat 的定位是轻量巡检。

不是每 30 分钟写一篇长报告。

图：HEARTBEAT.md 应该是短小、稳定、安全的检查清单，而不是大型任务说明书。

八、tasks: blocks：在 HEARTBEAT.md 里写间隔任务

HEARTBEAT.md 还支持一个结构化的 tasks: block。

它可以让不同检查有自己的 interval。

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
tasks:

- name: inbox-triage
  interval: 30m
  prompt: "Check for urgent unread emails and flag anything time sensitive."
- name: calendar-scan
  interval: 2h
  prompt: "Check for upcoming meetings that need prep or follow-up."

# Additional instructions

- Keep alerts short.
- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.

它的行为是：

  • OpenClaw 解析 tasks: block
  • 每个 task 按自己的 interval 判断是否 due
  • 只有 due 的 task 会进入本次 heartbeat prompt
  • 如果没有任务 due，可以跳过本次 heartbeat
  • task 的 last-run 时间存在 session state 里，正常重启后也能保留

这很适合多个轻量检查。

比如：

  • inbox-triage 每 30 分钟
  • calendar-scan 每 2 小时
  • writing-check 每天一次

但仍然要注意：

如果是明确的大型周期任务，优先用 Cron。

Heartbeat 里的 tasks 更适合轻量巡检。

九、Heartbeat 的默认频率

文档里提到默认间隔：

  • 通常是 30m
  • 某些 Anthropic OAuth / token auth 场景是 1h

你可以通过配置调整：

1
2
3
4
5
6
7
8
9
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m"
      }
    }
  }
}

如果要禁用 Heartbeat，可以设置：

1
2
3
4
5
6
7
8
9
{
  agents: {
    defaults: {
      heartbeat: {
        every: "0m"
      }
    }
  }
}

这里建议新手不要设置太短。

比如每 1 分钟一次，通常没有必要。

Heartbeat 是完整 agent turn，会消耗 tokens。

太频繁会贵，也会吵。

十、target: none 和 target: last

Heartbeat 运行后，结果要不要发出来，取决于 delivery 配置。

文档里提到：

1
target: "none"

是默认。

这表示：

Heartbeat 可以运行，但不主动对外投递消息。

如果你希望 Heartbeat 把 alert 发给最后联系过的用户，可以设置：

1
target: "last"

例如：

1
2
3
4
5
6
7
8
9
10
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last"
      }
    }
  }
}

也可以指定某个 channel 和 recipient。

比如 Telegram：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          accountId: "ops-bot"
        }
      }
    ]
  }
}

新手先记住：

target 控制 Heartbeat 结果发不发、发到哪里。

十一、showOk / showAlerts / useIndicator

Heartbeat 的可见性还可以按 channel 控制。

文档里提到三个开关：

  • showOk
  • showAlerts
  • useIndicator

showOk

是否显示 HEARTBEAT_OK 这种 OK 确认。

默认通常不显示。

showAlerts

是否显示真正的 alert 内容。

默认显示。

useIndicator

是否发 indicator 事件给 UI 状态面板。

默认启用。

一个典型配置：

1
2
3
4
5
6
channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true

这表示：

  • 没事不打扰
  • 有事提醒
  • UI 可以显示状态

如果三者都设为 false，OpenClaw 会直接跳过 heartbeat run，避免浪费模型调用。

十二、activeHours：限制活跃时间

Heartbeat 很容易变成打扰。

所以 active hours 很重要。

例如只想白天运行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "Asia/Shanghai"
        }
      }
    }
  }
}

这表示：

  • 早上 9 点到晚上 10 点之间运行
  • 其他时间跳过
  • 按北京时间判断

注意：

start 和 end 不能相同。

比如 08:00 到 08:00 会被当成零宽窗口，结果就是总是跳过。

如果你想全天运行，可以：

  • 不写 activeHours
  • 或写 00:00 到 24:00

图：Heartbeat 可以控制投递目标、OK 是否显示、alert 是否显示，以及只在指定 activeHours 内运行。

十三、lightContext 和 isolatedSession：降低成本

Heartbeat 是完整 agent turn。

如果每次都带很长上下文，成本会高。

OpenClaw 提供了两个很实用的选项：

  • lightContext
  • isolatedSession

lightContext

1
lightContext: true

表示 heartbeat 运行时只注入轻量 bootstrap context，通常只保留 HEARTBEAT.md。

适合 Heartbeat 只需要看清单，不需要整个工作区上下文的场景。

isolatedSession

1
isolatedSession: true

表示每次 Heartbeat 用一个 fresh session，不带过去对话历史。

文档里说，这可以显著降低每次 heartbeat 的 token 成本。

尤其是长期主会话很大时，非常有用。

推荐组合：

1
2
3
4
5
6
7
8
9
10
11
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        lightContext: true,
        isolatedSession: true
      }
    }
  }
}

这很适合只做轻量清单检查的 Agent。

十四、skipWhenBusy：忙的时候别添乱

Heartbeat 还可以在系统忙的时候跳过。

文档里提到：

  • Heartbeats 会自动在 cron work active 或 queued 时 defer
  • skipWhenBusy: true 可以进一步在 subagent 或 nested lanes 忙的时候也 defer

配置：

1
2
3
4
5
6
7
8
9
{
  agents: {
    defaults: {
      heartbeat: {
        skipWhenBusy: true
      }
    }
  }
}

这对资源有限的机器很有用。

比如你用本地模型、Ollama、小 VPS。

当 cron、subagent、nested command 已经很忙时，再跑 heartbeat 可能只是添堵。

所以可以让它等下一轮。

十五、手动唤醒 Heartbeat

除了定时 Heartbeat，也可以手动唤醒。

文档里给了命令：

1
openclaw system event --text "Check for urgent follow-ups" --mode now

这会 enqueue 一个 system event，并触发立即 heartbeat。

如果有多个 Agent 配了 heartbeat，manual wake 会让这些 Agent 的 heartbeat 都立即运行。

也可以设置：

1
--mode next-heartbeat

表示等下一次 scheduled tick。

这个功能适合：

  • 外部脚本提醒主会话注意某事
  • 手动触发一次轻量检查
  • 测试 heartbeat 是否工作

十六、Heartbeat 和 Webhook 的关系

第 19 课讲 /hooks/wake 时，其实已经接触了类似概念。

Webhook 可以把外部事件送进来。

Heartbeat 可以让主会话在合适时候处理这些事件。

比如：

  1. 外部系统调用 /hooks/wake
  2. Gateway 注入 system event
  3. Heartbeat 被唤醒
  4. Agent 判断是否需要提醒用户

所以 Webhook 和 Heartbeat 可以配合。

但它们职责不同：

  • Webhook：外部事件进来
  • Heartbeat：主会话周期性或被唤醒后处理注意事项

十七、Heartbeat 适合做哪些事？

Heartbeat 适合这些轻量任务。

1）提醒未处理事项

例如：

  • 有没有阻塞的任务
  • 有没有需要用户回复的事项
  • 有没有后台结果需要提醒

2）轻量 check-in

比如白天偶尔问一句：

1
目前没有紧急事项。如果你要继续写第 20 课，我可以接着做。

但注意，check-in 要克制。

3）后台完成事件提示

比如子 Agent 或 cron 完成了，需要主会话注意。

4）低频小检查

例如：

  • 每 2 小时看一次是否有 due task
  • 每天一次检查 HEARTBEAT.md 里的轻量项

5）维护型提醒

比如：

1
教程写作任务连续两天没有推进，需要提醒用户是否继续。

十八、Heartbeat 不适合做哪些事？

1）明确时间任务

比如每天 8 点晨报。

用 Cron。

2）大规模扫描

比如每 30 分钟扫所有日志、所有仓库、所有网页。

不适合。

3）高频监控

比如每 10 秒检查服务状态。

不适合 Agent，也不适合 Heartbeat。

4）敏感自动操作

比如自动删除、自动发布、自动改配置。

不要放 Heartbeat 里自动做。

5）每次都要长篇输出的任务

Heartbeat 最好大多数时候安静。

如果每次都输出长文，就违背了设计目标。

十九、一个好的 HEARTBEAT.md 示例

适合教程写作 Agent 的版本可以这样写：

1
2
3
4
5
6
# Heartbeat checklist

- 如果有正在等待用户确认的教程任务，请用一句话提醒。
- 如果最近一次写作任务已经完成，不要重复提醒。
- 如果发现某篇文章缺少 `.md` 文件发送请求，可以提醒补发一次。
- 如果没有明确需要用户注意的事，回复 HEARTBEAT_OK。

如果要加 structured tasks：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
tasks:

- name: writing-followup
  interval: 12h
  prompt: "检查是否有未完成的 OpenClaw 教程写作请求，只在确实需要用户注意时提醒。"
- name: article-artifacts
  interval: 24h
  prompt: "检查最近完成的教程是否已发送 .md 文件；如果已发送则不要提醒。"

# Rules

- 提醒要短，不超过 2 句话。
- 不要重复提醒已经完成的事项。
- 没有需要提醒的事，回复 HEARTBEAT_OK。

这个清单的特点是：

  • 任务少
  • 间隔长
  • 输出短
  • 不重复提醒
  • 不做高风险动作

这就是好的 Heartbeat。

二十、适合新手的 Heartbeat 提问模板

下面这些句式可以直接复制。

1）解释当前 Heartbeat 配置

1
请帮我检查当前 Heartbeat 配置，说明 every、target、activeHours、lightContext、isolatedSession 是否启用。不要修改配置。

2）设计 HEARTBEAT.md

1
请帮我写一个简短的 HEARTBEAT.md，只用于检查未完成提醒和后台结果，不要包含敏感信息，不要让 Agent 每次都长篇输出。

3）降低 Heartbeat 成本

1
请帮我把 Heartbeat 设计成低成本模式：lightContext=true，isolatedSession=true，并说明有什么影响。先不要改配置。

4）限制打扰时间

1
请设计一个 Heartbeat 配置，只在 Asia/Shanghai 的 09:00 到 22:00 之间运行，并且 OK 不显示，只显示真正 alerts。

5）关闭 Heartbeat

1
请告诉我如何禁用 Heartbeat，以及禁用后 HEARTBEAT.md 是否还会注入普通上下文。

6）区分 Cron 和 Heartbeat

1
这个需求是“每天 8 点生成报告”，还是“定期看看有没有需要提醒的事”？请判断应该用 Cron 还是 Heartbeat。

这些模板背后的重点是：

Heartbeat 要轻、短、少打扰。

二十一、常见坑

坑 1：把 Heartbeat 当 Cron 用

如果任务是明确时间和明确内容，例如每天 8 点报告，用 Cron。

Heartbeat 不是定时报告系统。

坑 2：HEARTBEAT.md 太长

Heartbeat 会反复读它。

太长会浪费 token，也容易让 Agent 每次输出太多。

坑 3：在 HEARTBEAT.md 放敏感信息

不要放 API key、token、手机号、私密账号等。

它会进入 prompt context。

坑 4：没有 HEARTBEAT_OK 规则

如果没事时不明确要求 HEARTBEAT_OK，Agent 可能每次都说点什么。

这会很吵。

坑 5：target 配错导致收不到 alert

默认 target: none。

如果你希望发到聊天，需要配置 target: last 或明确 channel / to。

坑 6：频率太高

每分钟一次通常没必要。

30 分钟、1 小时，甚至更长，通常更合理。

坑 7：activeHours 写成同一时间

比如：

1
activeHours: { start: "08:00", end: "08:00" }

这是零宽窗口，结果就是总跳过。

坑 8：忘了 busy defer

如果机器资源有限，建议考虑 skipWhenBusy: true。

避免 cron、subagent 和 heartbeat 抢资源。

二十二、Heartbeat 的安全原则

我建议记住这 7 条。

  1. Heartbeat 是轻量巡检，不是定时报告。
  2. 没事必须安静，用 HEARTBEAT_OK。
  3. HEARTBEAT.md 要短，不放敏感信息。
  4. 明确 target，否则默认可能不投递。
  5. 用 activeHours 限制打扰时间。
  6. 用 lightContext / isolatedSession 控制成本。
  7. 忙的时候可以 skipWhenBusy，别和后台任务抢资源。

图：Heartbeat 的安全使用原则：轻量、安静、低成本、少打扰、不放敏感信息、忙时避让。

二十三、这一课最值得记住的一句话

如果今天只记一句话，我建议你记这句：

Heartbeat 不是让 AI 定时干活，而是让 AI 定期判断有没有必要打扰你。

再补一句使用原则：

大多数心跳应该安静，少数真正重要的事才提醒。

二十四、总结

今天这节课，我们讲清楚了 OpenClaw 的 Heartbeat：

  1. Heartbeat 是周期性 Agent turn，用来发现是否有事需要提醒。
  2. Cron 是到点做明确任务，Heartbeat 是定期看看有没有事。
  3. Heartbeat 本身不创建 background task 记录。
  4. 默认 prompt 会读取 HEARTBEAT.md，并要求没事回复 HEARTBEAT_OK。
  5. HEARTBEAT_OK 是静默确认，避免无意义打扰。
  6. HEARTBEAT.md 是轻量检查清单，不应该写成长任务说明。
  7. tasks: block 可以让多个轻量检查按不同 interval 运行。
  8. target 控制是否投递、投递到哪里。
  9. activeHours 可以限制 Heartbeat 只在合适时间运行。
  10. lightContext、isolatedSession、skipWhenBusy 可以降低成本和资源冲突。

到这里，第四模块「多 Agent 与自动化」也告一段落了。

我们已经讲完：

  • sessions_spawn：怎么派生子 Agent
  • subagents：怎么管理子 Agent
  • Cron：怎么按时间自动工作
  • Webhook / Hooks：怎么按事件触发 AI
  • Heartbeat：怎么保持 Agent 活跃又不打扰

这五个概念合起来，OpenClaw 才真正从“聊天机器人”变成一个能长期运行、能自动处理任务、能响应事件的个人 AI 系统。

下一课预告

下一课开始，我们进入第五模块：多平台与节点。

第 21 课会讲：

多节点架构：手机 / VPS / 树莓派怎么协作

也就是：

  • 什么是 OpenClaw 节点
  • Gateway、手机、VPS、树莓派之间怎么分工
  • 为什么要多节点
  • 哪些任务适合跑在节点上
  • 多节点架构里最容易踩哪些坑

🦞 本文由八条撰写，持续更新中。